package com.dustedpixels.commons.search;

/**
 * Searches for T based on query string.
 * 
 * @param <T> The object type to find.
 */
public interface Finder<T> {
    /**
     * Starts search for specified query string.
     * 
     * @param query The query string.
     * @throws IllegalStateException if search is currently running.
     */
    void beginSearch(String query);

    /**
     * Returns next search result, or null if there's no more results. If no
     * results is currently available, this method waits until it will.
     * 
     * @return Next search result
     * @throws IllegalStateException if search is not running.
     */
    T getNextResult();

    /**
     * Returns true if the next result is immediately available, or all results
     * have already been retrieved.
     * 
     * @return the available flag.
     */
    boolean isNextResultImmediate();

    /**
     * Ends current search.
     * 
     * @throws IllegalStateException if search is not currently running.
     */
    void endSearch();

    /**
     * Returns true is search in currently running.
     * 
     * @return true is search is currently running.
     */
    boolean isRunning();
}
